

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Authenticating API requests &mdash; Apache Usergrid 1.0 documentation</title>
  

  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
  

  

  
    <link rel="top" title="Apache Usergrid 1.0 documentation" href="../index.html"/>
        <link rel="next" title="Revoking tokens (logout)" href="revoking-tokens-logout.html"/>
        <link rel="prev" title="Changing token expiration (time-to-live)" href="changing-token-time-live-ttl.html"/> 

  
  <script src="../_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-nav-search">
        

        
          <a href="../index.html" class="icon icon-home"> Apache Usergrid
        

        
        </a>

        
          
          
            <div class="version">
              1.0
            </div>
          
        

        
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

        
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
        
          
          
              <p class="caption"><span class="caption-text">Introduction</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../introduction/overview.html">Documentation Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/usergrid-features.html">Usergrid Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/data-model.html">Usergrid Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/async-vs-sync.html">Async vs. sync calls</a></li>
</ul>
<p class="caption"><span class="caption-text">Getting Started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../getting-started/creating-account.html">Creating an Usergrid Account</a></li>
<li class="toctree-l1"><a class="reference internal" href="../getting-started/creating-a-new-application.html">Creating a new application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../getting-started/using-a-sandbox-app.html">Using a Sandbox Application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../getting-started/using-the-api.html">Using the API</a></li>
</ul>
<p class="caption"><span class="caption-text">Data Storage</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/data-store-dbms.html">The Usergrid Data Store</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/optimizing-access.html">Data Store Best Practices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/collections.html">Collections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/entities.html">Entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Data Queries</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/querying-your-data.html">Querying your data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/query-parameters.html">Query parameters &amp; clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/operators-and-types.html">Query operators &amp; data types</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/advanced-query-usage.html">Advanced query usage</a></li>
</ul>
<p class="caption"><span class="caption-text">Entity Connections</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/connecting-entities.html">Connecting entities</a></li>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/retrieving-entities.html">Retrieving connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/disconnecting-entities.html">Disconnecting entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Push Notifications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/overview.html">Push notifications overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/adding-push-support.html">Adding push notifications support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/getting-started.html">Getting started with push notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/tutorial.html">Tutorial: Push notifications sample app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/registering.html">Registering with a notification service</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-notifiers.html">Creating notifiers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/managing-users-and-devices.html">Managing users and devices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-and-managing-notifications.html">Creating and managing notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/troubleshooting.html">Troubleshooting</a></li>
</ul>
<p class="caption"><span class="caption-text">Security &amp; Authentication</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="app-security.html">Security &amp; token authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="using-permissions.html">Using permissions</a></li>
<li class="toctree-l1"><a class="reference internal" href="using-roles.html">Using roles</a></li>
<li class="toctree-l1"><a class="reference internal" href="authenticating-users-and-application-clients.html">Authenticating users &amp; app clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="user-authentication-types.html">Authentication levels</a></li>
<li class="toctree-l1"><a class="reference internal" href="changing-token-time-live-ttl.html">Changing token expiration (time-to-live)</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Authenticating API requests</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#authenticating-with-access-tokens">Authenticating with access tokens</a></li>
<li class="toctree-l2"><a class="reference internal" href="#authenticating-with-client-id-and-client-secret">Authenticating with client ID and client secret</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="revoking-tokens-logout.html">Revoking tokens (logout)</a></li>
<li class="toctree-l1"><a class="reference internal" href="facebook-sign.html">Facebook sign in</a></li>
<li class="toctree-l1"><a class="reference internal" href="securing-your-app.html">Security best practices</a></li>
</ul>
<p class="caption"><span class="caption-text">User Management &amp; Social Graph</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-management.html">User management &amp; social graph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/working-user-data.html">Working with User Data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/group.html">Working with group data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/activity.html">Activity</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-connections.html">Social Graph Connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-connections.html#creating-other-connections">Creating other connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/messagee-example.html">App Example - Messagee</a></li>
</ul>
<p class="caption"><span class="caption-text">Geo-location</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../geolocation/geolocation.html">Geolocating your Entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Assets &amp; Files</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/uploading-assets.html">Uploading assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/retrieving-assets.html">Retrieving assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/folders.html">Folders</a></li>
</ul>
<p class="caption"><span class="caption-text">Counters &amp; Events</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/events-and-counters.html">Counters &amp; events</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html">Creating &amp; incrementing counters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html#decrementing-resetting-counters">Decrementing/resetting counters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html#using-counters-hierarchically">Using counters hierarchically</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/retrieving-counters.html">Retrieving counters</a></li>
</ul>
<p class="caption"><span class="caption-text">Organizations &amp; Applications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/managing.html">Organization &amp; application management</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/organization.html">Organization</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/application.html">Application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/admin-user.html">Admin user</a></li>
</ul>
<p class="caption"><span class="caption-text">API Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html">Methods</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#models">Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#sub-types">Sub-Types</a></li>
</ul>
<p class="caption"><span class="caption-text">Client SDKs</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../sdks/tbd.html">COMING SOON...</a></li>
</ul>
<p class="caption"><span class="caption-text">Installing the Stack</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../installation/ug1-deploy-to-tomcat.html">Usegrid 1: Deploying to Tomcat</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation/ug1-launcher-quick-start.html">Usegrid 1: Launcher Quick-start</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation/ug2-deploy-to-tomcat.html">Usergrid 2: Deploy to Tomcat</a></li>
</ul>
<p class="caption"><span class="caption-text">More about Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../reference/presos-and-videos.html">Presentations &amp; Videos</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/contribute-code.html">How to Contribute Code &amp; Docs</a></li>
</ul>

          
        
      </div>
      &nbsp;
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="../index.html">Apache Usergrid</a>
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="../index.html">Docs</a> &raquo;</li>
      
    <li>Authenticating API requests</li>
      <li class="wy-breadcrumbs-aside">
        
          
            <a href="../_sources/security-and-auth/authenticating-api-requests.txt" rel="nofollow"> View page source</a>
          
        
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="authenticating-api-requests">
<h1>Authenticating API requests<a class="headerlink" href="#authenticating-api-requests" title="Permalink to this headline">¶</a></h1>
<p>With the exception of the &#8216;sandbox&#8217; application that is created with
every Usergrid organization, all applications are secured by default.
This means that to access your data store, a valid access token must be
sent with all API requests to authenticate that the requester is
authorized to make API calls to the resources they are attempting the
access.</p>
<p>This article describes how to use access tokens to access the Usergrid
API, and how to manage access tokens, including revoking and changing
token time to live.</p>
<p>For information on generating access tokens/authenticating users and
clients, see <a class="reference external" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating users and application
clients</a>.</p>
<div class="section" id="authenticating-with-access-tokens">
<h2>Authenticating with access tokens<a class="headerlink" href="#authenticating-with-access-tokens" title="Permalink to this headline">¶</a></h2>
<p>When you obtain an access token, you must provide it with every
subsequent API call that you make. There are two ways to provide your
access token.</p>
<p>You can add the token to the API query string:</p>
<div class="highlight-python"><div class="highlight"><pre>https://&lt;usergrid-host&gt;/{org-name}/{app-name}/users?access_token={access_token}
</pre></div>
</div>
<p>You can include the token in an HTTP authorization header:</p>
<div class="highlight-python"><div class="highlight"><pre>Authorization: Bearer {access_token}
</pre></div>
</div>
<div class="admonition note"> <p class="first admonition-title"><p>Note</p>
  </p> <p class="last">


Note: The Usergrid documentation assumes you are providing a valid<p>access token with every API call whether or not it is shown explicitly
in the examples. Unless the documentation specifically says that you can
access an API endpoint without an access token, you should assume that
you must provide it. One application that does not require an access
token is the sandbox application. The Guest role has been given full
permissions (/** for GET, POST, PUT, and DELETE) for this application.
This eliminates the need for a token when making application level calls
to the sandbox app. For further information on specifying permissions,
see <a class="reference external" href="security-and-auth/using-permissions.html">Using Permissions</a>.</p>
</p></div></div>
<div class="section" id="authenticating-with-client-id-and-client-secret">
<h2>Authenticating with client ID and client secret<a class="headerlink" href="#authenticating-with-client-id-and-client-secret" title="Permalink to this headline">¶</a></h2>
<p>Another option for authenticating your API requests is using either your
organization client ID and client secret, or your application client ID
and client secret, which will authenticate your request as an
organization or application admin, respectively. Organization
credentials can be found in the &#8216;Org Overview&#8217; section of the admin
portal, and application credentials can be found in the &#8216;Getting
Started&#8217; section of the admin portal.</p>
<div class="admonition warning"> <p class="first admonition-title"><p>WARNING</p>
  </p> <p class="last">


Warning: For server-side use only You should never authenticate this<p>way from a client-side app such as a mobile app. A hacker could analyze
your app and extract the credentials for malicious use even if those
credentials are compiled and in binary format. See <a class="reference external" href="../security-and-auth/securing-your-app.html">Security Best
Practices</a> for
additional considerations in keeping access to your app and its data
secure.</p>
</p></div><p>This can be a convenient way to authenticate API requests, since there
is no need to generate and manage an access token, but please note that
you should be very cautious when implementing this type of
authentication. Organization-level authentication grants full permission
to perform any supported call against your organization and every
application in it, and application-level authentication grants full
permission to perform any supported call against all of the resources in
an application. Should your client id and client secret be compromised,
a malicious user would gain broad access to your organization or
application.</p>
<p>To authenticate using client id and secret, append the following
parameters to your request URL:</p>
<div class="highlight-python"><div class="highlight"><pre>client_id=&lt;your-client-id&gt;&amp;client_secret=&lt;your-client-secret&gt;
</pre></div>
</div>
</div>
</div>


           </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="revoking-tokens-logout.html" class="btn btn-neutral float-right" title="Revoking tokens (logout)" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="changing-token-time-live-ttl.html" class="btn btn-neutral" title="Changing token expiration (time-to-live)" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2013-2015, Apache Usergrid.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'../',
            VERSION:'1.0',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true
        };
    </script>
      <script type="text/javascript" src="../_static/jquery.js"></script>
      <script type="text/javascript" src="../_static/underscore.js"></script>
      <script type="text/javascript" src="../_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="../_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>